Add list support to `useFragment`, `useSuspenseFragment`, and `client.watchFragment` #12971

jerelmiller · 2025-10-13T19:42:59Z

Add support for lists with useFragment, useSuspenseFragment, and client.watchFragment.

const result = useFragment({
  fragment,
  from: [item1, item2]
});

console.log(result); // { data: [{...}, {...}], dataState: "complete", complete: true }

changeset-bot · 2025-10-13T19:43:03Z

🦋 Changeset detected

Latest commit: da3e9c2

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

apollo-librarian · 2025-10-13T19:43:59Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 11 changed, 0 removed

* (developer-tools)/react/(latest)/caching/cache-configuration.mdx
* (developer-tools)/react/(latest)/data/fragments.mdx
* (developer-tools)/react/(latest)/data/mutations.mdx
* (developer-tools)/react/(latest)/data/persisted-queries.mdx
* (developer-tools)/react/(latest)/data/queries.mdx
* (developer-tools)/react/(latest)/development-testing/testing.mdx
* (developer-tools)/react/(latest)/integrations/react-native.mdx
* (developer-tools)/react/(latest)/migrating/apollo-client-4-migration.mdx
* (developer-tools)/react/(latest)/performance/server-side-rendering.mdx
* (developer-tools)/react/(latest)/VERSIONING_POLICY.md
* (developer-tools)/react/(latest)/versioning-policy.md

Build ID: 51d9a8212bec1603ddd871d8
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/51d9a8212bec1603ddd871d8

pkg-pr-new · 2025-10-13T19:44:33Z

npm i https://pkg.pr.new/apollographql/apollo-client/@apollo/client@12971

commit: da3e9c2

src/react/hooks/useFragment.ts

phryneas · 2025-10-14T08:14:58Z

src/cache/core/cache.ts

+    }) as Observable<any>;
+
+    return Object.assign(observable, {
+      getCurrentResult: () => {


Could we return something with a changeTargets property here? That way we wouldn't need to unwatch/rewatch 999 unrelated elements if one id changed.

Yes! I was planning to do that next 🙂.

This is now implemented with reobserve which will only watch new ids and keep ids that haven't changed around 🙂

.changeset/old-singers-eat.md

jerelmiller added 6 commits October 13, 2025 12:54

Add failing tests for useFragment with lists

ae66ac9

Add initial pass implementation for useFragment with list

9f2e982

Update type test

1d52bea

Remove unneeded null return

ce739a5

Fix incorrect assertions

e5f722b

Ensure array changes identities to rerender updated data

314c248

jerelmiller commented Oct 13, 2025

View reviewed changes

src/react/hooks/useFragment.ts Outdated Show resolved Hide resolved

jerelmiller added 17 commits October 13, 2025 15:28

Add overloads for client/cache.watchFragment

93d3876

Handle masking

a29e004

Add failing list tests for watchFragment

87c09f0

Add first implementation in core

607d149

Don't allow for reobserve

4906e6a

Fix incorrect application of data masking in client.watchFragment

c73fb8f

Warn on invalid id sooner

456c372

Allow from as null internally in client.watchFragment

e9bb759

Switch to client.watchFragment with from array in useFragment

6b3d53d

Add tests for getCurrentResult

bb76dbe

Add getCurrentResult to watchFragment result

e5ef39e

Update test

7b6701e

Move comment down

326c76a

Use observable.getCurrentResult in useFragment

39a5300

Emit stable value to maintain referential equality

57a26f0

Move observable to useMemo

28ab461

Combine useDeepMemos

290c497

phryneas reviewed Oct 14, 2025

View reviewed changes

jerelmiller added 2 commits October 14, 2025 12:27

Rename lastResult to currentResult

6472131

Cast to any for now

ffbecf4

jerelmiller added 4 commits October 20, 2025 10:51

Rename WatchFragmentObservable to ObservableFragment

a5969a5

Prevent memory leak when unsubscribing from watch

4f3069b

Add another test to useSuspenseFragment

a77d2f2

TODO changeset

f66e681

jerelmiller commented Oct 20, 2025

View reviewed changes

.changeset/old-singers-eat.md Outdated Show resolved Hide resolved

jerelmiller added 5 commits October 20, 2025 17:16

Changesets

27029ee

Tweak comment

4ccc6aa

Simplify types

6250da6

Rename ApolloClient.WatchFragmentObservable to ObservableFragment

34d0269

Rerun api report

d4072da

jerelmiller force-pushed the jerel/use-fragment-list branch from c427a20 to d4072da Compare October 21, 2025 01:23

jerelmiller added 3 commits October 20, 2025 19:38

Change note to a tip

aa5edba

Fix typo

b0ad8c0

Add section for array with useFragment to docs

de61508

jerelmiller requested a review from a team as a code owner October 21, 2025 15:49

Fix typo

1d0e27c

jerelmiller force-pushed the jerel/use-fragment-list branch from f542b84 to 1d0e27c Compare October 21, 2025 16:09

jerelmiller added 2 commits October 22, 2025 14:07

Remove the observable from watches on unsubscribe

30418b3

More comments

14aff28

jerelmiller force-pushed the jerel/use-fragment-list branch from fffae5d to 14aff28 Compare October 22, 2025 20:22

Add test to ensure transitions work correctly

82e1a21

jerelmiller force-pushed the jerel/use-fragment-list branch from 5de32e7 to 82e1a21 Compare October 22, 2025 21:29

jerelmiller added 4 commits October 22, 2025 15:34

Update test to fail with too many watchers

cd1f626

Add comment

d73c809

Print watch ids

e57bbc2

Fix typo

da3e9c2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add list support to `useFragment`, `useSuspenseFragment`, and `client.watchFragment` #12971

Add list support to `useFragment`, `useSuspenseFragment`, and `client.watchFragment` #12971

jerelmiller commented Oct 13, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Oct 13, 2025 •

edited

Loading

Uh oh!

apollo-librarian bot commented Oct 13, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Oct 13, 2025 •

edited

Loading

Uh oh!

Uh oh!

phryneas Oct 14, 2025

Uh oh!

jerelmiller Oct 14, 2025

Uh oh!

jerelmiller Oct 16, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add list support to useFragment, useSuspenseFragment, and client.watchFragment #12971

Are you sure you want to change the base?

Add list support to useFragment, useSuspenseFragment, and client.watchFragment #12971

Conversation

jerelmiller commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

apollo-librarian bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

pkg-pr-new bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

phryneas Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

jerelmiller Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

jerelmiller Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add list support to `useFragment`, `useSuspenseFragment`, and `client.watchFragment` #12971

Add list support to `useFragment`, `useSuspenseFragment`, and `client.watchFragment` #12971

jerelmiller commented Oct 13, 2025 •

edited

Loading

changeset-bot bot commented Oct 13, 2025 •

edited

Loading

apollo-librarian bot commented Oct 13, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 13, 2025 •

edited

Loading